החלפת נכסי קריאייטיב של מודעות באמצעות Select URL API

קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

אתם יכולים להשתמש ב-Select URL API כדי לנצל את Shared Storage API כדי לקבוע איזה קריאייטיב יוצג למשתמש באתרים שונים.

מפרסמים או יוצרים של תוכן עשויים לרצות להחיל אסטרטגיות שונות של רוטציית תוכן על קמפיין, ולבצע רוטציה של התכנים או הקריאייטיב כדי לשפר את היעילות. אפשר להשתמש ב-Select URL API כדי להפעיל אסטרטגיות רוטציה שונות, כמו רוטציה רציפה ורוטציה עם חלוקה שווה, באתרים שונים.

באמצעות בחירת API של כתובת URL לצורך רוטציה של נכסי קריאייטיב, אפשר לאחסן נתונים כמו מזהה הקריאייטיב, מספר הצפיות ואינטראקציות של משתמשים, כדי לקבוע לאילו משתמשים יוצגו נכסי הקריאייטיב באתרים שונים.

מידע נוסף על ה-API הבסיסי ועל אופן הבחירה זמין במסמכי התיעוד של Select URL API.

כדאי לנסות סבב קריאייטיב

כדי להתנסות בסבב הקרנת קריאייטיב, צריך לוודא ש-Select URL API ו-Shared Storage מופעלים:

• בשדה chrome://settings/content/siteData, בוחרים באפשרות Allow sites to save data on your device או Delete data sites have saved to your device when you close all windows.
• בchrome://settings/adPrivacy/sites, בוחרים באפשרות Site-suggested ads.

בהדגמה של Shared Storage תוכלו לנסות גרסה פעילה של דוגמאות הקוד שמפורטות במסמך הזה.

הדגמה עם דוגמאות קוד

בדוגמה הזו:

• creative-rotation.js הוא הסקריפט של הצד השלישי שמגדיר את התוכן שרוצים לבצע בו רוטציה, יחד עם כל הנתונים שקובע את התוכן הבא לבחירה ולהצגה, כמו משקלים בדוגמה הזו. הדף של בעל התוכן הדיגיטלי מפעיל את הסקריפט הזה. הסקריפט הזה קורא ל-worklet של אחסון משותף כדי לקבוע איזה תוכן להציג על סמך הנתונים הזמינים באחסון ועל סמך רשימת כתובות ה-URL לבחירה.

• creative-rotation-worklet.js הוא ה-worklet של האחסון המשותף של הצד השלישי, שמחפש את אסטרטגיית הרוטציה, מחשב איזה תוכן לפרסם בשלב הבא ומחזיר את קטע התוכן הזה.

איך פועל הדמו

1. כשמשתמש נכנס לדף של בעל התוכן הדיגיטלי, הדף טוען את הסקריפט creative-rotation.js של הצד השלישי. סקריפט סבב הקריאייטיב אחראי על הטעינה וההפעלה של ה-worklet של האחסון המשותף. הסקריפט מספק לקריאה של ה-worklet רשימה של כתובות URL לבחירה.
2. ב-worklet, אם האחסון המשותף עדיין לא הופעל, האחסון מופעל עם שיטת הרוטציה הראשונית של הקריאייטיב והאינדקס של הקריאייטיב. שיטת הרוטציה הראשונית שבה נעשה שימוש בדמו הזה היא שיטת רוטציה רציפה.
3. ה-worklet קורא את מצב הסבב מהאחסון המשותף ומחזיר את האינדקס של המודעה הבאה. במקרה של מצב רוטציה רציף, המערכת מעדכנת גם את מדד הקריאייטיב באחסון המשותף בערך החדש שישמש בקריאה הבאה.ה-worklet מחזיר אובייקט FencedFrameConfig או אובייקט URN אטום על סמך ערך resolveToConfig ששימש בקריאה ל-selectURL.
4. סקריפט הקריאייטיב-רוטציה מציג את המודעה שנבחרה במסגרת מוקפת או ב-iframe. במסמך 'עיבוד מודעה' מוסבר על סוגי ההחזרים.
5. כשמשתמש משנה את סטטוס הסיבוב, ה-worklet של האחסון המשותף מעדכן את הערך של סטטוס הסיבוב של הקריאייטיב שנשמר באחסון המשותף.
6. כשמעמיסים מחדש את דף בעל התוכן הדיגיטלי, שלבים 1-4 חוזרים על עצמם כדי לאפשר בחירת את המודעה הבאה שמוצגת על סמך שיטת הרוטציה שנבחרה.

דוגמאות קוד

בהמשך מפורטות דוגמאות הקוד של creative-rotation.js ושל creative-rotation-worklet.js.

creative-rotation.js

const contentProducerUrl = 'https://your-server.example';

// Ad config with the URL of the ad, a probability weight for rotation, and the clickthrough rate.
const DEMO_AD_CONFIG = [
  {
    url: `${contentProducerUrl}/ads/ad-1.html`,
    weight: 0.7,
  },
  {
    url: `${contentProducerUrl}/ads/ad-2.html`,
    weight: 0.2,
  },
  {
    url: `${contentProducerUrl}/ads/ad-3.html`,
    weight: 0.1,
  },
];

async function setRotationMode(rotationMode) {
  // Load the worklet module
  const creativeRotationWorklet = await window.sharedStorage.createWorklet(
    `${contentProducerUrl}/url-selection/creative-rotation-worklet.js`,
    { dataOrigin: 'script-origin' }
  );

  await creativeRotationWorklet.run('set-rotation-mode', {
    data: { rotationMode }
  });
  console.log(`creative rotation mode set to ${rotationMode}`);
}

async function injectAd() {
  // Load the worklet module
  const creativeRotationWorklet = await window.sharedStorage.createWorklet(
    `${contentProducerUrl}/url-selection/creative-rotation-worklet.js`,
    { dataOrigin: 'script-origin' }
  );

  const urls = DEMO_AD_CONFIG.map(({ url }) => ({ url }));

  // Resolve the selectURL call to a fenced frame config only when it exists on the page
  const resolveToConfig = typeof window.FencedFrameConfig !== 'undefined';

  // Run the URL selection operation to determine the next ad that should be rendered
  const selectedUrl = await creativeRotationWorklet.selectURL('creative-rotation', urls, {
    data: DEMO_AD_CONFIG,
    resolveToConfig
  });

  const adSlot = document.getElementById('ad-slot');

  if (resolveToConfig && selectedUrl instanceof FencedFrameConfig) {
    adSlot.config = selectedUrl;
  } else {
    adSlot.src = selectedUrl;
  }
}

injectAd();

creative-rotation-worklet.js

class SelectURLOperation {
  async run(urls, data) {
    // Initially set the storage to sequential mode for the demo
    await SelectURLOperation.seedStorage();

    // Read the rotation mode from Shared Storage
    const rotationMode = await sharedStorage.get('creative-rotation-mode');

    // Generate a random number to be used for rotation
    const randomNumber = Math.random();

    let index;

    switch (rotationMode) {
      /**
       * Sequential rotation
       * - Rotates the creatives in order
       * - Example: A -> B -> C -> A ...
       */
      case 'sequential':
        const currentIndex = await sharedStorage.get('creative-rotation-index');
        index = parseInt(currentIndex, 10);
        const nextIndex = (index + 1) % urls.length;

        console.log(`index = ${index} / next index = ${nextIndex}`);

        await sharedStorage.set('creative-rotation-index', nextIndex.toString());
        break;

      /**
       * Evenly-distributed rotation
       * - Rotates the creatives with equal probability
       * - Example: A=33% / B=33% / C=33%
       */
      case 'even-distribution':
        index = Math.floor(randomNumber * urls.length);
        break;

      /**
       * Weighted rotation
       * - Rotates the creatives with weighted probability
       * - Example: A=70% / B=20% / C=10%
       */
      case 'weighted-distribution':
        console.log('data = ', JSON.stringify(data));
        // Find the first URL where the cumnulative sum of the weights
        // exceed the random number. The array is sorted by the weight
        // in descending order.
        let weightSum = 0;
        const { url } = data
          .sort((a, b) => b.weight - a.weight)
          .find(({ weight }) => {
            weightSum += weight;
            return weightSum > randomNumber;
          });

        index = urls.indexOf(url);
        break;

      default:
        index = 0;
    }

    console.log(JSON.stringify({ index, randomNumber, rotationMode }));
    return index;
  }

  // Set the mode to sequential and set the starting index to 0.
  static async seedStorage() {
    await sharedStorage.set('creative-rotation-mode', 'sequential', {
      ignoreIfPresent: true,
    });

    await sharedStorage.set('creative-rotation-index', 0, {
      ignoreIfPresent: true,
    });
  }
}

class SetRotationModeOperation {
  async run({ rotationMode }) {
    await sharedStorage.set('creative-rotation-mode', rotationMode);
  }
}

// Register the operation as 'creative-rotation'
register('creative-rotation', SelectURLOperation);
register('set-rotation-mode', SetRotationModeOperation);

הדרכה עם צילומי מסך

1. כדי לגשת לחלוקת הקריאייטיב באמצעות Select URL API ואחסון משותף, עוברים לכתובת https://shared-storage-demo.web.app/. בוחרים את ההדגמה 'סבב מודעות'.

2. בוחרים לבדוק את הדמו בתור 'בעל תוכן דיגיטלי א''. תתבצע הפניה לכתובת https://shared-storage-demo-publisher-a.web.app/creative-rotation. הדף טוען תוכן ממוספר על סמך נתוני רוטציית הקריאייטיב שנשמרו ב-Shared Storage, שאפשר לגשת אליהם דרך Select URL API. מצבי הדגמה של סבב נכסי הקריאייטיב הם סבב ברצף, חלוקה שווה וחלוקה משוקלת. ה-worklet מבצע את הלוגיקה כדי לבחור את התוכן שיופיע ב-iframe. בתמונה הבאה מוצג דף בעל התוכן הדיגיטלי.

   
   

3. כדי לראות מה מאוחסן ב-Shared Storage, עוברים אל Application (אפליקציה) -> Shared Storage (אחסון משותף) ב-Chrome DevTools. נוצרות שתי רשומות לאחסון משותף. נפח אחסון ריק זמין למקור https://shared-storage-demo-publisher-a.web.app. הוא יכיל אחסון ספציפי למקור הזה, והוא יישאר ריק במהלך הדגמה שלנו כי לבעלי התוכן הדיגיטלי אין צורך לכתוב לאחסון המשותף. לתשומת ליבכם: אחסון דומה ייוצר לבעל האתר השני כשתיכנסו לדף הזה במועד מאוחר יותר לצורך הדגמה.

   
   

4. תיווצר עוד רשומה של Shared Storage למקור https://shared-storage-demo-content-producer.web.app. זהו האחסון של ה-iframe של הצד השלישי שמוטמע בדף של בעל התוכן הדיגיטלי. האחסון הזה ישמש לשיתוף נתונים בין שני בעלי האפליקציות הזמינים, כדי לתאם את בחירת הקריאייטיב. האחסון המשותף הזה ישמש לשמירת מידע על הקריאייטיב המוצג ועל אסטרטגיית הרוטציה, באמצעות שמירת שני צמדי מפתח/ערך. המפתח הראשון שנעשה בו שימוש בדמו הוא creative-rotation-index, והערך שלו הוא אינדקס הקריאייטיב הנוכחי במצב רציף. המפתח השני הוא creative-rotation-mode, שמכתיב את שיטת הרוטציה שבה נעשה שימוש.

   
   

5. רענון הדף במצב רציף יוביל להצגת נכס הקריאייטיב הבא ברצף 1, 2, 3, 1, …, הערך של המפתח creative-rotation-index ישתנה בהתאם לאינדקס של נכס הקריאייטיב שמוצג במצב רציף.

   
   

6. שינוי מצב הרוטציה של הקריאייטיב באמצעות לחצני הבקרה יגרום לעדכון הערך של המפתח creative-rotation-mode בשיטה המתאימה. הקוד של ה-worklet ישתמש בזה כדי לבחור את הקריאייטיב הבא שיוצג ב-iframe. חשוב לזכור שהערך שנשמר בשדה creative-rotation-index לא משתנה במצבי רוטציה שאינם 'רציף'.

   
   

7. עוברים לדף של 'בעל התוכן הדיגיטלי ב' בכתובת https://shared-storage-demo-publisher-b.web.app/creative-rotation. במצב רצף, הקריאייטיב שמוצג צריך להיות הקריאייטיב הבא ברצף שמוצג כשנכנסים לכתובת ה-URL של 'בעל התוכן הדיגיטלי א''. כשבודקים את האחסון המשותף של יוצר התוכן, רואים שגם 'בעל האתר א'' וגם 'בעל האתר ב' משתפים את אותו אחסון ומשתמשים בהגדרות שם כדי לבחור את הקריאייטיב הבא שיוצג ואת אסטרטגיית הרוטציה שבה ישתמשו.

   
   

8. נפח האחסון המשותף של 'בעל התוכן הדיגיטלי ב' ריק, בדומה לנפח האחסון המשותף של 'בעל התוכן הדיגיטלי א'.

   
   

   תרחישים לדוגמה

   בקטע הזה מפורטים כל תרחישי השימוש הזמינים של Select URL API. נמשיך להוסיף דוגמאות ככל שנקבל משוב ונמצא תרחישי בדיקה חדשים.

   • החלפת נכסי הקריאייטיב של המודעות: אחסון נתונים, כמו מזהה הקריאייטיב והאינטראקציה של המשתמש, כדי לקבוע אילו נכסי קריאייטיב המשתמשים יראו באתרים שונים.
   • בחירת נכסי קריאייטיב של מודעות לפי תדירות: אתם יכולים להשתמש בנתוני מספר הצפיות כדי לקבוע אילו נכסי קריאייטיב המשתמשים רואים באתרים שונים.
   • הרצת בדיקות A/B: אפשר להקצות משתמש לקבוצת ניסוי, ולאחר מכן לאחסן את הקבוצה הזו ב-Shared Storage כדי לגשת אליה באתרים שונים.
   • התאמה אישית של חוויית השימוש ללקוחות מוכרים: שיתוף תוכן מותאם אישית וקידומים מכירה על סמך סטטוס ההרשמה של המשתמש או מצבים אחרים של המשתמש.

יצירת מעורבות ושיתוף משוב

חשוב לדעת שההצעה ל-Select URL API נמצאת כרגע בשלבי פיתוח ודיון, והיא כפופה לשינויים.

נשמח לשמוע את דעתכם על Select URL API.

• הצעה: בודקים את ההצעה המפורטת.
• דיון: תוכלו להצטרף לדיון המתמשך כדי לשאול שאלות ולשתף את התובנות שלכם.

אפשר להתעדכן

• רשימת תפוצה: תוכלו להירשם לרשימת התפוצה שלנו כדי לקבל את העדכונים וההודעות האחרונים לגבי ממשקי ה-API של Select URL ו-Shared Storage.

דרושה לך עזרה?

• תמיכה למפתחים: במאגר התמיכה למפתחים של ארגז החול לפרטיות תוכלו ליצור קשר עם מפתחים אחרים ולקבל תשובות לשאלות שלכם.